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1.  Purpose 


The  purpose  of  this  document  is  to  provide  detailed  information  on  how  to 
effectively  build  an  Android  application  to  monitor  network  traffic  using  open 
source  packet  capture  (pcap)  libraries.^ 

2.  Configuration  Used 

The  following  list  is  the  software  and  hardware  used  for  development  and  testing; 

Operating  System  (OS):  Red  Hat  Enterprise  Linux  (RHEL),  version  6.5 
Android  Development  Tools  (ADTs),  Version  22.3.0-887826 
Saferoot^ 

Samsung  Galaxy  S3 
Dell  Precision  T7400 

o  8  GB  memory 

o  Intel  Xeon  X5472  Central  Processing  Unit  (CPU) 

■  64-bit  quad  and  dual-core 

■  3.00  GHz 

Open  source  pcap  libraries 
Oracle  VirtualBox^  -  optional 
Android  OS  ISO  for  xSb"^  -  optional 
Android  Software  Development  Kit  (SDK)^ 

Android  Native  Development  Kit  (NDK)^ 

3.  Overview 


In  the  field  of  network  monitoring,  the  pcap  Application  Programming  Interface 
(API)  is  a  well-known  set  of  open  source  libraries  for  capturing  network  traffic. 
Because  the  pcap  API  is  written  in  C,  the  codes  can  be  ported  to  an  Android  device 
natively  to  improve  speed  performance  while  monitoring  high-volume  network 
traffic. 

4.  Android  Tool  Kits  Setup 

To  setup  the  Android  tool  kits,  download  Android  SDK^  and  NDK.^  Then, 
decompress  the  2  files  to  the  local  bin  path.  Afterward,  setup  the  local  .bashrc  with 
the  correct  Android  environment  settings,  assuming  that  home/userl/bin  is  where 
the  tool  kits  are  installed.  See  Pig.  1 . 
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export  ANDROI D_SDK=/home /user 1 /bin/ adt-bundle-linux- 
x86_64-20131030/sdk 

export  ANDROI D_NDK=/home /user 1 /bin/ android-ndk-r 9 
export  PATH=$ANDROID_SDK/tools : $ANDROID_SDK/platf orm- 
tools:  $PATH 

export  ANDROI D_HOME=/home /user 1 /bin/ adt-bundle-linux- 
x86  64-20131030/sdk 


Fig.  1  Example  of  .bashrc  with  Android  tool  kit  settings 

Ensure  that  “ndk-build”  command  can  be  executed  if  NDK  is  setup  correctly.  From 
ECLIPSE,  an  integrated  development  environment  (IDE),  part  of  the  Android  SDK, 
ensure  that  the  SDK  location  is  set  to  the  correct  directory.  To  perform  this 
operation,  open  Eclipse,  go  to  <Preference->Android>.  The  SDK  location  edit  line 
should  be  set  to  the  path  where  SDK  was  installed  (i.e.,  </home/userl/bin/adt- 
bundle-linux-x86_64-20 131030/ sdk>) . 

5.  Rooting  Android 


Because  the  pcap  library  requires  root  privileges,  rooting  of  the  Android  device  is 
necessary.  Refer  to  the  Technical  Note  (TN),  Rooting  Android  Device^  for  more 
detail. 

6.  Setup  Android  on  VirtualBox 


To  speed  up  the  debugging  process  without  using  the  actual  Android  device,  or  the 
very  slow  Android  virtual  machine,  deploy  the  Android  OS  on  VirtualBox.  Refer 
to  the  TN,  Android  Virtual  Machine  (VM)  Setup  on  Linux^  for  additional 
information. 

7.  Cross-Compile  Android  Native  Code  on  x86 


CROSS-COMPILER  can  create  executable  code  for  a  processor  other  than  the  one  on 
which  the  compiler  is  running.  I  used  VirtualBox  to  run  the  Android  OS  VM  on  an 
x86  processor.  Because  this  processor  is  a  nonARM-based  processor,  it  requires 
cross  compilation. 

To  add  this  capability  to  a  processor  that  runs  on  a  different  platform,  create  an 
Android  makefile  (Application.mk)  for  the  current  Android  project  under  the  <jni> 
subdirectory.  Make  sure  to  use  uppercase  characters  in  the  Application.mk  file.  An 
example  of  this  file  is  shown  in  Fig.  2. 
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APP_STL  :=  gnustl_static 

APP  ABI  :=  armeabi  armeabi-v7a  x86 


Fig.  2  Example  of  Application  mk  file 

The  <x86>  is  the  keyword  used  in  this  makefile  to  speeify  the  x86  proeessor  type, 
whieh  is  used  to  cross-eompile  applications  that  run  on  the  Android  OS  using  an 
x86  processor.  After  the  processor  type  is  added,  simply  perform  the  normal  ndk- 
build  steps^.  The  native  code  is  now  ready  for  deployment. 

The  Android  application  can  use  the  Java  Native  Interface  (JNI)  to  communicate 
with  the  native  codes.  As  a  result,  there  is  no  need  to  be  concerned  about  building 
a  separate  executable  for  native  calls.  However,  if  the  application  is  required  to 
spawn  a  native  process,  then  it  is  necessary  to  have  a  separate  build  for  each 
processor-based  executable.  In  order  to  deploy  the  native  executable  from  the 
Android  package,  this  executable  must  be  copied  or  saved  under  the  <asset>  path 
of  the  project  directory. 

There  are  many  options  that  allow  a  programmer  to  distribute  processor-based 
executables.  The  easiest  method  is  to  have  a  separate  processor  build  package  for 
deployment.  Another  more  complicated  option  is  to  create  a  separate  path  for  a 
processor-based  directory  under  the  project’s  <asset>  path.  For  example, 
<project/asset/x86>  for  x86  and  <project/asset/arm>  can  be  used  for  ARM 
processors.  To  deploy  the  correct  type  of  executable  when  running  the  application, 
the  CPU  type  should  be  obtained.  The  processor  type  on  the  device  can  be  retrieved 
by  using  the  BufferedReader  class  from  the  device’s  </proc/cpuinfo>  fide.  Figure  3 
shows  an  example  of  how  to  retrieve  the  CPU  information. 
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Private  String  getCpuInfo() 

{ 

StringBuffer  sb  =  new  StringBuffer(); 

sb . append ( "abi :  ") . append (Build. CPU  ABI) . append ( "\n" ) ; 
if  (new  File  ("/proc/cpuinfo" ). exists  0  )  { 

try 

{ 

Buf f eredReader  br  =  new  Buf f eredReader (new 
FileReader (new  File ("/proc/cpuinfo") ) ) ; 

String  data; 

while  ((data  =  br . readLine ( ) )  !=  null)  { 

sb . append (aLine  +  "\n"); 

} 

if  (br  !=  null)  { 
br . close ( ) ; 

} 

}  catch  (lOException  e)  { 
e . printStackTrace ( )  ; 

} 

} 

//  info  from  the  cpu  file 
return  sb . toString ( ) ; 

} 


Fig.  3  Example  of  how  to  get  CPU  information  in  code 

After  the  CPU  type  is  obtained,  the  AssetManager  in 
<android.eontent.res.AssetManager>  API  can  be  used  to  extract  the  native 
executable.  The  codes  shown  in  Fig.  4  are  an  example  of  how  to  retrieve  files  from 
the  asset  folder. 
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Private  void  copyFileFromAssets (String  assetPath,  String 
filename,  String  toPath) 

{ 

AssetManager  assetManager  =  this . getAssets ( ) ; 

InputStream  in  =  null; 

OutputStream  out  =  null; 

try  { 

in  =  assetManager . open (assetFilename ) ; 
out  =  new  FileOutputStream (newFileName ) ; 

byte[]  buffer  =  new  byte [1024]; 
int  read; 

while  ((read  =  in . read (buffer) )  !=  -1)  { 

out . write (buff er,  0,  read) ; 

} 

in . close ( ) ; 
in  =  null; 
out . flush ( ) ; 
out . close ( ) ; 
out  =  null; 

}  catch  (Exception  e)  { 

Log. e (mServiceName ,  e . getMessage ( ) ) ; 


Fig.  4  Example  of  retrieving  files  from  the  asset  folder 


8.  Building  Application  with  Native  Codes 


8.1  Calling  Native  Codes  Using  JNI 

One  way  for  an  Android  application  to  interact  with  native  codes  is  to  use  JNI.  JNI 
provides  the  cross-platform  between  Java  and  C/C++.  When  calling  C  from  Java, 
it  is  necessary  to  have  the  Java-to-C  calling  method  be  static.  The  keyword  “static 
native”  should  be  used.  The  C++  method  has  to  be  static  as  well.  The  example  in 
Fig.  5  illustrates  how  Java  calls  C  using  JNI. 
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Public  int  callNativeExample ( ) 

{ 

String  config  =  "config"; 

String  pcap  =  "pcap"; 

String  datafile  =  "file"; 

String  savefile  =  "save"; 

//  calls  the  native  code 

int  ret  =  nalnitElide ( config,  pcap,  datafile, 
saveFile) ; 

} 

//  JNI  native  call  declaration 

private  static  native  int  nalnitElide ( String  config.  String 
pCap,  String  datafile.  String  saveFile) ; 
private  static  native  String  naStartElideTest ( )  ; 
private  static  native  void  naStopService ( ) ; 

static  { 

System. loadLibrary ("Test Jni") ; 

} 


Fig.  5  Example  of  Java  calling  C  using  JNI 

The  above  examples  show  3  methods:  1)  Method  naInitElide()  passes  4  strings  to 
the  JNI  interfaee  method  and  returns  an  integer;  2)  Method  naStartElideTest()  has 
no  passing  parameter  and  returns  a  string;  and  3)  Method  naStopEIideTest()  has  no 
passing  and  no  return  parameters.  These  methods  belong  to  the  native  library  ealled 
“TestJni”.  The  library  must  be  deelared  as  statie.  After  these  methods  are  ereated 
and  saved  as  a  Java  fde,  the  javah  utility  program  ean  be  used  to  create  the  C/C++ 
interface  header.  An  example  of  the  usage  is  shown  in  Eig.  6. 

Javah  -verbose  -classpath  $ANDROID  SDK/platforms/android- 
1 9/android . j ar : bin/classes  -jni  -d  jni 
com. example . elidetest . ElideTestService 


Fig.  6  Example  of  compiling  C/C++  header  file  from  Java  using  javah 

As  shown  in  Eig.  6,  a  C/C++  based  header  file  will  be  created  based  on  the  number 
of  native  methods  that  are  created.  In  this  example,  I  assume  that  ElideTestService 
is  an  <ElideTestService.java>  file  and  that  <com.example.elidetest>  is  the 
namespace.  The  “-classpath”  option  points  to  where  the  <android.jar>  file  is.  The 
-d  option  specifies  where  to  place  the  output  header  files.  The  header  file  can  be 
used  as  definition  for  the  methods  used  later — just  need  to  fill  in  the  contents.  An 
example  of  the  C/C++  implementation  using  JNI  is  shown  in  Eig.  7. 
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tinclude  <jni.h> 

#include  "com  example  elidetest  ElideTestService . h" 

/* 

*  Class:  com  example  elidetest  ElideTestService 

*  Method:  nalnitElide 

*  Signature: 

(Lj ava /I ang/ String; Ljava/lang/String; Ljava/lang/String; Ljav 
a/lang/String; ) I 

* 

*  (JNIEnv  *,  jclass,  jstring,  jstring,  jstring,  jstring); 

V 

JNIEXPORT  jint  JNICALL 

Java  com  example  elidetest  ElideTestService  nalnitElide 

(JNIEnv  *env,  jclass  clazz,  jstring  config,  jstring 
pCap,  jstring  datafile,  jstring  saveFile) 

{ 

//  converts  Java  String  to  const  char* 
const  char  *  datafile  =  env->GetStringUTFChars 
(datafile,  0 ) ; 

params . datafile  =  datafile; 

const  char  *  config  =  env->GetStringUTFChars  (config, 

0)  ; 

params . configFile  =  config; 

const  char  *_pCap  =  env->GetStringUTFChars  (pCap,  0) ; 
params . pcapFile  =  _pCap; 

const  char  *  saveFile  =  env->GetStringUTFChars 
(saveFile,  0) ; 

params . pcapSaveFile  =  saveFile; 

//  release  buffers  allocated  by  the  env 
env->ReleaseStringUTFChars  (config,  config) ; 
env->ReleaseStringUTFChars  (datafile,  datafile) ; 
env->ReleaseStringUTFChars  (pCap,  pCap) ; 
env->ReleaseStringUTFChars  (saveFile,  saveFile); 

//  do  your  stuffs  here 

return  0; 

j _ 

Fig.  7  Example  of  using  JNI  in  C 

The  C/C++  method  name  uses  a  very  striet  deelaration  for  the  Android  JNI.  The 
method  name  must  follow  the  eorreet  naming  eonvention  for  it  to  work  properly. 
For  this  reason,  the  javah  program  eomes  in  very  handy  beeause  it  ereates  the 
header  automatieally.  Onee  the  native  eodes  are  written,  eompile  the  eodes  using 
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the  usual  <ndk-build>  command  via  command  shell  under  the  project’s  <jni> 
directory.  It  will  build  the  native  codes  object  library  for  you.^ 

8.2  Calling  Native  Codes  from  an  Android  Application 

The  purpose  of  calling  native  codes  from  an  Android  application  is  to  allow  the 
application  itself  to  have  the  ability  to  start  as  “root”.  This  application  can  spawn  a 
process  that  requires  administrative  privileges.  Under  the  current  design  Android 
development  requirement,  an  Android  Graphical  User  Interface  (GUI)  application 
cannot  directly  call  any  native  API  that  requires  administrative  permissions,  as  in 
the  case  of  pcap’s  <pcap_open_live()>  method.  To  overcome  this  obstacle,  the 
application  needs  to  spawn  the  super  user  (su)  process,  which  requires  the  user  to 
grant  permission.  After  “su”  is  granted  by  the  user,  this  process  will  need  to  spawn 
a  shell  process  and  then  calls  the  process  that  requires  “root”  access.  An  example 
of  the  “su”  granting  process  using  native  code  is  illustrated  in  Fig.  8. 
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private  static  j ava . lang . Process  mElideProcess  =  null; 
private  9escry9  bCreated  =  false; 
private  DataOutputStream  mOS  =  null; 
try  { 

mElideProcess  =  Runtime . getRuntime (). exec ( "su" ,  null, 
null )  ; 

//  Attempt  to  write  a  file  to  a  root-only 
mOS  =  new 

DataOutputStream (mElideProcess . getOutputStream ( ) ) ; 
mReader  =  new  Buf f eredReader (new 

InputStreamReader (mElideProcess . getInputStream ( ) ) ) ; 

if  (null  !=  mOS  &&  null  !=  mReader) 
bCreated  =  true; 

} 

catch  (Exception  e) 

{ 

//  Can't  get  root! 
mRoot  =  false; 

mRootMsg  =  "createProcess  failed:  su  "  + 
e . getMessage ( )  ; 

} 

if  (bCreated  ==  true) 

{ 

try  { 

mOS . writeBytes ("id\n")  ; 
mOS . flush ( ) ; 

String  currUid  =  mReader . readLine ()  ; 

9escry9  exitSu  =  false; 

if  (true  ==  currUid. contains ("uid=0")  ) 

{ 

//  do  something  after  permission  is 

granted. 

//  ie.  Call  your  own  process 
//  pcapElide  is  an  example  of  the  command 
//  that  is  using 
try  { 

String  cmd  =  "./pcapElide"; 
mOS . writeBytes (cmd)  ; 
mOS . flush ( ) ; 

}  catch  (lOException  e)  { 

//  TODO  Auto-generated  catch  block 
e . printStackTrace  ( ) ; 

} 


Fig.  8  Example  of  the  “su”  granting  process  using  native  code 
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9.  Retrieve  Live  Network  Traffic  via  pcap 


There  are  many  ways  to  capture  live  network  traffic  on  an  Android  device. 
However,  one  way  to  capture  network  traffic  is  to  use  the  pcap  library  in  native 
codes.  This  method  is  the  most  preferred  for  optimal  performance  in  obtaining 
network  traffic  data  for  analyses. 

To  open  network  traffic,  the  <pcap_open_live()>  method  is  used.  The  2  API 
methods  to  retrieve  network  data  once  the  device  is  opened  are  <pcap_next()>  and 
<pcap_loop()>.  I  performed  experiments  using  both  API  methods.  At  constant 
network  traffic,  I  discovered  that  if  an  Android  device  receives  data  speed  lower 
than  100  kbps,  the  2  API  methods  did  not  have  any  performance  issues.  However, 
with  constant  incoming  data  rate  higher  than  250  kbps,  <pcap_next()>  does  not 
respond  to  the  caller.  In  other  words,  the  API  just  stayed  in  an  infinite  loop  without 
returning  back  to  the  caller.  On  the  other  hand,  <pcap_loop()>  uses  the  callback 
handler  capability,  and  it  has  no  problem  handling  any  network  speed.  If  the 
network  speed  is  too  fast,  it  simply  drops  the  packets  and  continues  its  required 
request.  An  example  of  how  to  open  and  retrieve  network  data  using  pcap  is  shown 
in  Fig.  9. 
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pcap  t*  getPCapFileDescrpitor ( const  string  SpcapOrDevice ) 

{ 

pcap  t*llescry  =  NULL; 

char  errbuf [PCAP_ERRBUF_SIZE] ;  //  256 

bpf  u  int32  pMask;  /*  subnet  mask  */ 

bpf_u_int32  pNet;  /*  ip  address*/ 

//  use  this  if  it  is  an  offline  file 

//llescry  =  pcap_open_of f line (pcapOrDevice . c_str ( ) , 
errbuf) ; 

pcap_if_t  *alldevs,  *d; 
char  dev_buff[64]  =  { 0 } ; 
int  i  =0; 

//  Prepare  a  list  of  all  the  devices 
if  (pcap  f indalldevs ( Salldevs ,  errbuf)  ==  -1) 

{ 

cout<<  "no  device  found\n"; 
return  NULL; 


cout  <<  "flags:  "  <<  alldevs->f lags  <<  "\n"; 

//  Print  the  list  to  user 
//  so  to  see  the  right  selection  is  made 
bool  bFoundDevice  =  false; 
for  (d=alldevs;  d;  d=d->next) 

{ 

if  (pcapOrDevice  ==  d->name) 

//  requested  device  found 
bFoundDevice  =  true; 


if  (bFoundDevice  ==  false) 

{ 

cout  <<  "device  "  <<  pcapOrDevice  <<  "  cannot  be 
found  as  active\n"; 

return  llescry; 


//  fetch  the  network  address  and  network  mask 
pcap_lookupnet (pcapOrDevice . c_str 0 ,  &pNet,  SpMask, 
errbuf) ; 


//  Now,  open  device  for  sniffing  none  promiscuous  =  0 
llescry  =  pcap_open_live (pcapOrDevice . c_str () ,  //  name 
of  the  device 


65536,  //  guarantees  that  the  whole  packet  will  be 
captured  on  all  the  link  layers 

0,  //  none  promiscuous  mode 

1000,  //  read  timeout  1  sec 

errbuf) ;  //  error  buffer 

//  no  longer  need  device  list 
pcap_f reealldevs (alldevs) ; 

} 

/*  Callback  function  invoked  by  libpcap  for  every  incoming 
packet  */ 

void  packet  handler (u  char  *param,  const  struct  pcap  pkthdr 
*header,  const  u_char  *pkt_data) 

{ 

//  do  your  own  processing  here 

} 

//  example  of  opening  device 

pcap_t  *pCap  =  getPCapFileDescrpitor ("wlanO" ) ; 

//  example  of  setting  pcap  loop  after  device  is  opened 
if  (pcap  loop(pCap,  -1,  (pcap  handler ) packet  handler,  NULL) 
==-!)“ 

{ 

//  problem  with  pcap  loop 

} 


Fig.  9  Example  of  how  to  open  and  retrieve  network  data  nsing  pcap 


10.  Conclusions 


Network  traffic  capturing  on  Android  using  pcap  with  native  codes  is  relatively 
new.  This  report  serves  as  a  guide  for  any  developer  creating  an  application  on 
Android  to  take  advantage  of  the  proven  open  source  speedy  performance  to 
monitor  or  capture  network  traffic  using  pcap. 
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List  of  Symbols,  Abbreviations,  and  Acronyms 


ADT 

Android  Development  Tool 

API 

Applieation  Programming  Interface 

CPU 

Central  Processing  Unit 

GUI 

Graphical  User  Interface 

IDE 

integrated  development  environment 

JNI 

Java  Native  Interface 

NDK 

Native  Development  Kit 

OS 

Operating  System 

pcap 

packet  capture 

RHEL 

Red  Hat  Enterprise  Linux 

SDK 

Software  Development  Kit 

su 

super  user 

TN 

Technical  Note 

VM 

Virtual  Machine 
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